Skip to content

keeper: add reserve/commit/mark journal primitives - #583

Merged
mfw78 merged 1 commit into
dev/m1from
sdk/538-journal-reserve-api
Jul 24, 2026
Merged

keeper: add reserve/commit/mark journal primitives#583
mfw78 merged 1 commit into
dev/m1from
sdk/538-journal-reserve-api

Conversation

@mfw78

@mfw78 mfw78 commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

What

Add the durable journal primitives to nexum-sdk's Journal: reserve, park, commit, release, mark, reserved, plus the Mark and Reservation types. Marker values are tag-first so a reservation and a commit can never collide by presence: RESERVED = [0x01] ++ be64(next_eligible_epoch_s) ++ body, COMMITTED = [0x02], and a legacy empty marker reads as committed for back-compat.

mark classifies by value: absent is None, empty or a leading 0x02 is Committed, and any other first byte (including a corrupt tag) is Reserved, so an unreadable marker forces a later reconcile rather than a skip. reserved enumerates exactly that Reserved set with each body and backoff.

This PR is dormant: it adds the primitives and retains record/contains for the observe path, and changes no sweep. The sweeps adopt these in the follow-up that also adds the reconcile pass, so a reserve write is never shipped without the scan that resolves it.

Why

The submit-dedup journal needs to distinguish an in-flight reservation from a settled receipt to close the post-submit-fault duplicate window without introducing a silent drop. contains cannot, since presence alone conflates the two. mark reads the value; its rustdoc now warns that contains must not guard a reserve/commit journal.

Testing

cargo fmt --all -- --check, cargo clippy --workspace --all-targets --all-features --locked -D warnings, all 17 guest wasms, cargo nextest run --workspace --all-features --locked (the new L1 unit tests: mark distinguishes reserved/committed/absent/legacy-empty/corrupt-tag; the mark/reserved agreement invariant; reserve/commit/release/park round-trips), cargo test --doc, RUSTDOCFLAGS=-D warnings cargo doc --workspace --no-deps --locked, scripts/check-venue-agnostic.sh, scripts/check-cow-orderbook-only.sh.

AI Assistance

Implemented with Claude Code.

Closes #538

@mfw78
mfw78 force-pushed the sdk/538-journal-reserve-api branch from c9f4a69 to a401cfa Compare July 24, 2026 09:33
@mfw78 mfw78 changed the title sdk: reserve/commit/release journal over the existing store verbs keeper: add reserve/commit/mark journal primitives Jul 24, 2026
@mfw78
mfw78 merged commit c9b4d5d into dev/m1 Jul 24, 2026
7 checks passed
@mfw78
mfw78 deleted the sdk/538-journal-reserve-api branch July 24, 2026 11:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant